
//Copyright 1997-2009 Syrinx Development, Inc.
//This file is part of the Syrinx Web Application Framework (SWAF).
// == BEGIN LICENSE ==
//
// Licensed under the terms of any of the following licenses at your
// choice:
//
//  - GNU General Public License Version 3 or later (the "GPL")
//    http://www.gnu.org/licenses/gpl.html
//
//  - GNU Lesser General Public License Version 3 or later (the "LGPL")
//    http://www.gnu.org/licenses/lgpl.html
//
//  - Mozilla Public License Version 1.1 or later (the "MPL")
//    http://www.mozilla.org/MPL/MPL-1.1.html
//
// == END LICENSE ==
using System;
using System.ComponentModel;
using System.Xml;
using System.Collections;
	
using Swaf.Container;

namespace Swaf.BizObj
{
	/// <summary>
	/// Represents a list of business objects
	/// </summary>
	public interface IBizObjList : INameAddressSupport, ICloneable, IList, IEnumerable
	{

		/// <summary>
		/// Each IBizObjList is a homogenious list of a specific type of bizobj.  Even when
		/// the list is empty, this property will return the type of bizobj that is in the list.
		/// </summary>
		IBizObjDefinition objectType{get;}

		/// <summary>
		/// The actual count of elements contained in the list.  Should always be >= 0.
		/// </summary>
		int numElements{get;}

		/// <summary>
		/// Allows indexed access to specific elements in the list.  This is an optional method to implement
		/// and can throw an exception indicating that it isn't implemented.
		/// </summary>
		IBizObj this[int index] { get;set;}

		IBizObj insertNew();
		IBizObj insertNewMakeCopy(IBizObj obj);
		void removeAt(int index);
		IBizObjCursor createCursor();
		void refresh();

		IKeyedBizObjList getIndex(string fieldList);
		/// <summary>
		/// When a new bizobj has been added to the list and its values populated, calling this
		/// will ensure the new bizobj is updated in any indexes that exist.  Really only valid
		/// for the full bizobj list.
		/// </summary>
		/// <param name="insertedObj"></param>
		void refreshIndexesFromBizObj(IBizObj insertedObj);

		/// <summary>
		/// Searches for a bizobj in this list that matches the key value provided.
		/// </summary>
		/// <remarks>This method uses <c>this.Source.getObject</c> to let is use its own
		/// mechanism to search for objects.  The this.Source member should be implemented
		/// to optimize this call so that the search doesn't continueously do a binary search.</remarks>
		/// <param name="keyFieldList">A comma delimited list of field names from the bizobj type 
		/// list that is used to search for a matching bizobj.</param>
		/// <param name="key">The value to compare against the bizobj when looking for a match.</param>
		/// <returns>The first bizobj in the sort order of the keyFieldList that matches
		/// the key provided.</returns>
		IBizObj search(string keyFieldList, object key);
		IBizObj search(string keyFieldList, object key, bool findNearestMatch);

		IBizObjSource Source {get;}

		string Name {get;set;}

		string Xml {get;}
		string getXml(string options);
		string getXml(string name, bool setOnly, bool dirtyOnly, bool newOnly, bool getBasic, bool getObjs, bool getILists, bool getSysVals, XmlTextWriter xmlOut);
		string getXml(string name, string decoInfo, bool setOnly, bool dirtyOnly, bool newOnly, bool getBasic, bool getObjs, bool getILists, bool getSysVals, XmlTextWriter xmlOut);
	}
}